/*
 * Tencent is pleased to support the open source community by making
 * WCDB available.
 *
 * Copyright (C) 2017 THL A29 Limited, a Tencent company.
 * All rights reserved.
 *
 * Licensed under the BSD 3-Clause License (the "License"); you may not use
 * this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 *       https://opensource.org/licenses/BSD-3-Clause
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.tencent.wcdb.database;

import java.util.List;


/**
 * Callback interface for SQLite trace events.
 */
public interface SQLiteTrace {

    class TraceInfo<T> {
        public final T info;
        public final long time;
        public final int tid;

        TraceInfo(T info_, long time_, int tid_) {
            info = info_;
            time = time_;
            tid = tid_;
        }
    }

    /**
     * Called when a SQL statement finished execution.
     *
     * @param db    database on which the statement was executed
     * @param sql   statement executed
     * @param type  type of the statement. See {@link com.tencent.wcdb.DatabaseUtils#getSqlStatementType}
     * @param time  time spent on execution, in milliseconds
     */
    void onSQLExecuted(SQLiteDatabase db, String sql, int type, long time);

    /**
     * Called when database connection is successfully obtained by a thread.
     *
     * @param db        database on which the connection was obtained
     * @param sql       statement about to be executed
     * @param waitTime  time spent on waiting for available connection, in milliseconds
     * @param isPrimary whether the primary connection (write connection) is obtained
     */
    void onConnectionObtained(SQLiteDatabase db, String sql, long waitTime, boolean isPrimary);

    /**
     * Called when connection pool is blocked by other statement execution
     * for a long time.
     *
     * @param db        database on which connection pool is blocked
     * @param sql       statement to be executed
     * @param requests  list of statement being executed
     * @param message   message generated by the connection pool
     */
    void onConnectionPoolBusy(SQLiteDatabase db, String sqlWaiting, long waitTime,
                              boolean wantPrimaryConnection,
                              List<TraceInfo<String>> sqlRunning,
                              List<TraceInfo<StackTraceElement[]>> longLastingActions);

    /**
     * Called on database corruption detected. This is valid on default error handler only.
     * See {@link com.tencent.wcdb.DatabaseErrorHandler}
     *
     * @param db    the corrupted database
     */
    void onDatabaseCorrupted(SQLiteDatabase db);
}
